﻿// -----------------------------------------------------------------------
// <copyright file="NotificationListener.cs" company="Zen Design Corp">
// TODO: Update copyright text.
// </copyright>
// -----------------------------------------------------------------------

namespace Zen.BlackBerry.Acknowledgement
{
	using Zen.BlackBerry.Push;

	/// <summary>
	/// Abstract class that defines common functionality for the notification
	/// message listeners.
	/// </summary>
	/// <remarks>
	/// Every custom notification listener that is meant to be registered with
	/// the SDK (in <see cref="INotificationListenerService"/>) must extend
	/// this class and set the listener type to one of the values in the
	/// <see cref="ListenerType"/> enumeration.
	/// </remarks>
	public abstract class NotificationListener
	{
		/// <summary>
		/// Gets the type of the listener.
		/// </summary>
		/// <value>The type of the listener.</value>
		public abstract ListenerType ListenerType
		{
			get;
		}

		/// <summary>
		/// Processes the result notification.
		/// </summary>
		/// <param name="pushId">
		/// The push-id to which the notification pertains.
		/// </param>
		/// <param name="listenerType">
		/// Type of the notification message.
		/// Note: ListenerType.Any will never be passed here
		/// </param>
		/// <param name="pushOutcome">
		/// The outcome of pushing to a particular address.
		/// </param>
		/// <remarks>
		/// <para>
		/// The client address (eg: PIN) in the result notification from the PPG
		/// was mapped to the address in the provided <see cref="PushOutcome"/>
		/// using the currently known mapping. This may lead in incorrect results
		/// if a subscriber or device swap occurred after the push request was
		/// issued.
		/// </para>
		/// <para>
		/// Note: The <see cref="PushOutcome.Address"/> may return "*" (without quotes)
		/// that indicates that the code applies to all addresses of the push with
		/// the specified push id.
		/// </para>
		/// </remarks>
		public abstract void Process(string pushId, ListenerType listenerType, PushOutcome pushOutcome);
	}
}
